Eclipse Platform
Pre-release 3.0

org.eclipse.team.core.subscribers
Class BackgroundEventHandler

java.lang.Object
  extended byorg.eclipse.team.core.subscribers.BackgroundEventHandler

public abstract class BackgroundEventHandler
extends Object

This class provides the infrastucture for processing/dispatching of events in the background. This is useful to allow blocking operations to be more responsive by delegating event processing and UI updating to background job.

This is also useful for scheduling changes that require a workspace lock but can't be performed in a change delta.

Since:
3.0

Nested Class Summary
static class BackgroundEventHandler.Event
          Resource event class.
 
Constructor Summary
protected BackgroundEventHandler()
           
 
Method Summary
protected  void createEventHandlingJob()
          Create the job used for processing the events in the queue.
protected abstract  void dispatchEvents()
          Notify clients of processed events.
protected abstract  String getErrorsTitle()
          Return the text to be displayed as the title for any errors that occur.
 Job getEventHandlerJob()
           
abstract  String getName()
          Return the name of the handler, which is used as the job name.
protected  void handleException(CoreException e)
          Handle the exception by recording it in the errors list.
protected  boolean isQueueEmpty()
          Return whether there are unprocessed events on the event queue.
 boolean isShutdown()
           
protected  void jobDone(IJobChangeEvent event)
          This method is invoked when the processing job completes.
protected abstract  void processEvent(BackgroundEventHandler.Event event, IProgressMonitor monitor)
          Process the event in the context of a running background job.
protected  IStatus processEvents(IProgressMonitor monitor)
          Process events from the events queue and dispatch results.
protected  void queueEvent(BackgroundEventHandler.Event event)
          Queue the event and start the job if it's not already doing work.
protected  void schedule()
          Schedule the job to process the events now.
 void shutdown()
          Shutdown the event handler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BackgroundEventHandler

protected BackgroundEventHandler()
Method Detail

createEventHandlingJob

protected void createEventHandlingJob()
Create the job used for processing the events in the queue. The job stops working when the queue is empty.


jobDone

protected void jobDone(IJobChangeEvent event)
This method is invoked when the processing job completes. The default behavior of the handler is to restart the job if the queue is no longer empty and to clear the queue if the handler was shut down.


schedule

protected void schedule()
Schedule the job to process the events now.


getName

public abstract String getName()
Return the name of the handler, which is used as the job name.

Returns:
the name of the handler

getErrorsTitle

protected abstract String getErrorsTitle()
Return the text to be displayed as the title for any errors that occur.

Returns:
the title to display in an error message

shutdown

public void shutdown()
Shutdown the event handler. Any events on the queue will be removed from the queue and will not be processed.


isShutdown

public boolean isShutdown()
Returns:
Returns whether the handle has been shutdown.

queueEvent

protected void queueEvent(BackgroundEventHandler.Event event)
Queue the event and start the job if it's not already doing work. If the job is already running then notify in case it was waiting.


isQueueEmpty

protected boolean isQueueEmpty()
Return whether there are unprocessed events on the event queue.

Returns:
whether there are unprocessed events on the queue

processEvents

protected IStatus processEvents(IProgressMonitor monitor)
Process events from the events queue and dispatch results. This method does not directly check for or handle cancelation of the provided monitor. However, it does invoke processEvent(Event) which may check for and handle cancelation by shuting down the receiver.


dispatchEvents

protected abstract void dispatchEvents()
                                throws TeamException
Notify clients of processed events.

Throws:
TeamException

handleException

protected void handleException(CoreException e)
Handle the exception by recording it in the errors list.

Parameters:
e -

processEvent

protected abstract void processEvent(BackgroundEventHandler.Event event,
                                     IProgressMonitor monitor)
                              throws CoreException
Process the event in the context of a running background job. Subclasses may (but are not required to) check the provided monitor for cancelation and shut down the receiver by invoking the shutdown() method.

Parameters:
event -
monitor -
Throws:
CoreException

getEventHandlerJob

public Job getEventHandlerJob()
Returns:
Returns the eventHandlerJob.

Eclipse Platform
Pre-release 3.0

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.